Authenticate Webhook Requests

Relworx signs webhook requests so you can (optionally) verify that requests are generated by Relworx and not a third-party pretending to be Relworx. If your application exposes sensitive data, you may want to be sure the requests are coming from Relworx. This isn't required, but offers an additional layer of verification.

Verifying Request Signatures

Relworx includes an additional HTTP header with webhook POST requests, Relworx-Signature, which will contain the signature for the request. To verify a webhook request, generate a signature using the same key that Relworx uses and compare that to the value of the Relworx-Signature header.

Get your webhook authentication key

When you create a business account, a key is automatically generated. You can also view and reset the key from the settings section on your business account view page.

Generate a signature

In your code that receives or processes webhook requests:

1. Create a string with the webhook's URL, exactly as you entered it (including any query strings, if applicable). Relworx always signs webhook requests with the exact callback URL you provided for your request. A difference as small as including or removing a trailing slash will prevent the signature from validating.

2. Extract the timestamp and signature from the header. Relworx includes a timestamp in the Relworx-Signature header to mitigate replay attacks. A replay attack is when an attacker intercepts a valid payload and its signature, then re-transmits them. Because this timestamp is part of the signed payload, it is also verified by the signature, so an attacker cannot change the timestamp without invalidating the signature. If the signature is valid but the timestamp is too old, you can have your application reject the payload. Split the header, using the , character as the separator, to get a list of elements. Then split each element, using the = character as the separator, to get a prefix and value pair. The value for the prefix t corresponds to the timestamp, and v corresponds to the signature. Sample Relworx-Signature "relworx-signature": "t=1561370460,v=fgrSxEFI/z6Twr6xZogRYnKCfew="

3. Concatenate signature timestamp to webhook URL.

4. Sort the request's POST variables alphabetically by key. Append each POST variable's key and value to the URL string, with no delimiter. Only include POST variables shown in sample code. status, customer_reference, internal_reference

5. Hash the resulting string with HMAC-SHA256, using your webhook signing key to generate a hex-encoded signature.

6. Compare the hex-encoded signature that you generated to the signature provided in the Relworx-Signature HTTP header.

Sample PHP implementation to generate verification signature:

/**
 * @param string $webhook_key the webhooks authentication key
 * @param string $url the webhook url
 * @param string $timestamp the signature timestamp
 * @param array $params the requests POST parameters
 */

//Only include these from POST data
$params = array(
  "status" => "success",
  "customer_reference" => "shdfjsue789sh8jshuehu",
  "internal_reference" => "jshfufehkshffkseuhfskahakhuefak",
);

function generateSignature($webhook_key, $timestamp, $url, $params) {
    $signed_data = $url;
    $signed_data .= $timestamp;
    ksort($params);
    foreach ($params as $key => $value) {
        $signed_data .= strval($key);
        $signed_data .= strval($value);
    }

    return hash_hmac('sha256', $signed_data, $webhook_key, false);
}